[docs] Document mixed-quality staging package discovery in aspire add - #1505
[docs] Document mixed-quality staging package discovery in aspire add#1505aspire-repo-bot[bot] wants to merge 1 commit into
Conversation
Documents microsoft/aspire#19426 - Fix mixed-quality staging package discovery. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
aspire-repo-bot
Bot
added
the
docs-from-code
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
There was a problem hiding this comment.
Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.
Note
This error may be related to your runner configuration. You can now configure runners for Copilot code review separately from Copilot cloud agent by creating a copilot-code-review.yml file with your setup steps. Read the docs for details.
David Pine (IEvangelist)
left a comment
David Pine (IEvangelist)
left a comment
There was a problem hiding this comment.
Docs-accuracy review — PR #1505
Phase A source of truth: microsoft/aspire release/13.5 @ 45f7776ddb51ba976a32ece224ef8b23ed989a91
Claims extracted: 6 · verified 3 · verified-with-nuance 1 · contradicted 2 · unverifiable 0
Phase B (doc-tester, blind): 2 routes exercised (/reference/cli/commands/aspire-add/, /reference/cli/install-script/#options) — 0 critical, 0 warnings, 6 passed checks, 2 knowledge gaps.
⚠️ The source PR this documents — microsoft/aspire#19426 (milestone 13.6) — is not present onrelease/13.5, the branch this doc PR targets (verified:git log release/13.5 --grep=19426is empty). Claims were therefore verified against the code that actually ships onrelease/13.5. On that branch theaspire adddiscovery path does not gate on CLI quality the way the new note describes (see inline comment).
Verdict: REQUEST_CHANGES — Phase A found 2 contradicted claims (both on the added note, line 30). Phase B is clean (rendering, links, and copy buttons all work).
Phase A — Claim verification
Two contradicted claims are posted as inline comments on the added note:
- C3 — behavior: "A
releasequality CLI continues to search stable packages only." Theaspire addsearch always includes the implicitPackageChannelQuality.Bothchannel regardless of CLI quality, so prerelease packages remain discoverable on areleaseCLI. "stable packages only" is inaccurate onrelease/13.5. - C4 — CLI surface: the version option is spelled
--versiononly; there is no-valias onaspire add(-vis the root CLI's print-version flag).
Verified / verified-with-nuance claims (evidence) — 4
| # | Claim | Verdict | Evidence (release/13.5 @ 45f7776) |
|---|---|---|---|
| C1 | `-Quality | --qualityinstall option with valuesrelease/staging/dev; anchor /reference/cli/install-script/#options` |
verified |
| C2 | On a staging/dev quality CLI, aspire add discovers both stable and prerelease packages |
verified-with-nuance | PackageChannel.CreateImplicitChannel = Quality.Both (PackageChannel.cs:740-748), always in search (IntegrationPackageSearchService.cs:89-100). Nuance: discovery is not gated by CLI quality — the implicit Both channel always participates; feed provenance is the real driver. |
| C5 | Aspire.Hosting.Azure.Kubernetes intentionally ships prerelease even in a stable-shaped build |
verified | Aspire.Hosting.Azure.Kubernetes.csproj: <SuppressFinalPackageVersion>true</SuppressFinalPackageVersion> + <EnablePackageValidation>false</EnablePackageValidation> |
| C6 | Friendly name azure-kubernetes for aspire add |
verified | IntegrationPackageSearchService.GenerateFriendlyName: Id.Replace("Aspire.Hosting.","").Replace('.','-').ToLowerInvariant() → azure-kubernetes |
Phase B — Doc-tester results (blind to source)
Routes exercised: /reference/cli/commands/aspire-add/ and /reference/cli/install-script/#options.
| Metric | Count |
|---|---|
| Critical issues | 0 |
| Warnings | 0 |
| Passed checks | 6 |
| Knowledge gaps | 2 |
Critical issues: none.
Warnings: none.
Passed checks
- The added note renders as a "Note" admonition with the custom title "Integration discovery on prerelease CLI builds".
- Inline code
Aspire.Hosting.Azure.Kubernetesrenders inside the note. - The -Quality|--quality link →
/reference/cli/install-script/#optionsresolves: target page loads, the#optionsheading exists, and-Quality|--qualityis shown there (0 console errors on the target page). - The new example renders under Examples as an "Aspire CLI" code frame —
aspire add azure-kubernetes— with a working copy button ("Copied aspire add azure-kubernetes to clipboard"). - Page console clean: 0 errors, 0 warnings (the only 404 seen was an initial no-trailing-slash request, immediately served at the canonical trailing-slash URL).
- Structure/navigation intact: the note sits in the intro (no spurious TOC entry); the example is correctly nested as "4 of 4" in the existing Examples list.
Recommendations: Optional — link the note's "release quality" caveat to the existing aspire add kafka --version … example so readers can jump straight to version-pinning.
Knowledge gaps (blind-user perspective — not verifiable from docs alone)
- The claim that a
releasequality CLI "continues to search stable packages only" is presented without an in-page demonstration; a blind user cannot confirm it. (Phase A found this contradicted against source — see C3.) - Both the new note and the page's existing Options list say
-v, --version; a blind user would type-v, which cannot be validated from the docs. (Phase A found-vis not an alias of the add version option — see C4.)
| <Include relativePath="reference/cli/includes/project-search-logic-description.md" /> | ||
|
|
||
| :::note[Integration discovery on prerelease CLI builds] | ||
| When you're running a `staging` or `dev` quality CLI (see [`-Quality|--quality`](/reference/cli/install-script/#options)), `aspire add` discovers both stable and prerelease integration packages, because some integrations — such as `Aspire.Hosting.Azure.Kubernetes` — intentionally ship as prerelease even during a stable-shaped staging build. A `release` quality CLI continues to search stable packages only, but can still add a specific prerelease integration version with the `-v, --version` option. |
There was a problem hiding this comment.
Contradicted (behavior) — release/13.5 @ 45f7776. This note says a release quality CLI "continues to search stable packages only," but on release/13.5 the aspire add discovery path does not gate on CLI quality. IntegrationPackageSearchService.GetSearchChannelsAsync always includes the implicit channel, and PackageChannel.CreateImplicitChannel(...) is hard-coded to PackageChannelQuality.Both (src/Aspire.Cli/Packaging/PackageChannel.cs:740-748). Its own comment: the implicit Quality.Both channel "must always participate so prerelease packages are reachable even when the explicit pin is Stable-quality" (IntegrationPackageSearchService.cs:97-100). A Both channel issues both prerelease:false and prerelease:true queries (PackageChannel.cs:321-328), so a release CLI still discovers prerelease packages from the ambient feed — "stable packages only" is inaccurate on this branch.
Also: the source PR this documents (microsoft/aspire#19426, milestone 13.6) is not present on release/13.5, which this PR targets. The staging/dev-vs-release split may hold on 13.6 but not on 13.5. Consider re-scoping to 13.5 behavior (prerelease integrations are discoverable via the always-present implicit Both channel; a release CLI typically selects the stable version by default) or retargeting once a 13.6 branch exists.
| <Include relativePath="reference/cli/includes/project-search-logic-description.md" /> | ||
|
|
||
| :::note[Integration discovery on prerelease CLI builds] | ||
| When you're running a `staging` or `dev` quality CLI (see [`-Quality|--quality`](/reference/cli/install-script/#options)), `aspire add` discovers both stable and prerelease integration packages, because some integrations — such as `Aspire.Hosting.Azure.Kubernetes` — intentionally ship as prerelease even during a stable-shaped staging build. A `release` quality CLI continues to search stable packages only, but can still add a specific prerelease integration version with the `-v, --version` option. |
There was a problem hiding this comment.
Contradicted (CLI surface) — release/13.5 @ 45f7776. --version is correct, but the -v short form is not. aspire add's version option is registered as new("--version") with no -v alias (src/Aspire.Cli/Commands/AddCommand.cs:42 and :69; contrast --source, -s on the next line). -v is the root CLI's print-version flag (RootCommand.cs:271 versionOption.Aliases.Add("-v"); CommonOptionNames.cs:12 VersionShort = "-v"), so aspire add <name> -v <version> would not pin a package version. Suggest writing just --version. (Heads-up: the page's existing Options list also uses -v, --version for this option — out of scope here, but worth reconciling.)
Adam Ratzman (adamint)
left a comment
Adam Ratzman (adamint)
left a comment
There was a problem hiding this comment.
I do not have anything to add beyond the existing review threads.
Documents changes from microsoft/aspire#19426
@mitchdennyTargeting
release/13.5— the latest release branch onmicrosoft/aspire.dev— becauserelease/13.6(from the source PR milestone13.6) does not exist there.Why this PR is needed
The source PR fixes
aspire addpackage discovery so that, on stable-shaped staging CLI builds, integrations that intentionally remain prerelease (likeAspire.Hosting.Azure.Kubernetes) are still discoverable from both C# and TypeScript AppHosts. Previously the TypeScript/polyglot path used an explicit stable-only staging channel and those integrations disappeared from search results. The PR body includes a "User-facing usage" section (aspire add azure-kubernetes), which triggered thepr_body_has_user_facing_sectionsignal.Documentation changes
aspire addcommand reference explaining thatstaging/devquality CLI builds discover both stable and prerelease integration packages, and thatreleasequality CLI builds remain stable-only (with the-v, --versionfallback still available for a specific prerelease version).aspire add azure-kubernetesin the context of a stable-shaped staging CLI.Files modified
src/frontend/src/content/docs/reference/cli/commands/aspire-add.mdx(updated existing page)No new pages were created; this updates the existing
aspire addreference page.